Existing login modules

Here is some brief description of existing login modules:

• OAuthLoginModule - It's useful only if OAuth authentication is enabled (disabled by default. See OAuth - Authentication with social network accounts with instructions on how to enable it.
  If OAuth is used and OAuth authentication succeed, the special Identity object will be created and saved into shared state map (Map, which is shared between all login modules), so that this Identity object can be used by JBossAS7LoginModule or other login modules in the JAAS chain.

• SSODelegateLoginModule - It's useful only if SSO authentication is enabled (disabled by default. It can be enabled through properties in configuration.properties file and in this case it delegates the work to another real login module for SSO integration. If SSO is disabled, SSODelegateLoginModule is simply ignored. See Central Authentication Service (CAS)#Configuration properties details for more details.
  If SSO is used and SSO authentication succeed, the special Identity object will be created and saved into shared state map (Map, which is shared between all login modules), so that this Identity object can be used by JBossAS7LoginModule or other login modules in the JAAS chain.

• JBossAS7LoginModule - Most important login module, which is normally used to perform whole authentication by itself. First it checks if Identity object has been already created and saved into sharedState map by previous login modules (like SSODelegateLoginModule, CustomMembershipLoginModule or SharedStateLoginModule). If not, it triggers real authentication of user with usage of Authenticator interface and it will use Authentication.validateUser(Credential[] credentials) which performs real authentication of username and password against OrganizationService and portal identity database. See Authenticator and RolesExtractor for details about Authenticator and about Identity objects.
  In the JbossAS7LoginModule.commit method, the Identity object is registered to IdentityRegistry, which will be used later for authorization. Also some JAAS principals (UserPrincipal and RolesPrincipal) and assigned to our authenticated Subject. This is needed for JBoss AS server, so that it can properly recognize name of logged user and his roles on JBoss AS level.

There is couple of other login modules, which are not active by default, but you can add them if you find them useful.

• CustomMembershipLoginModule- special login module, which can be used to add user to some existing groups during the successful login of this user. The group name is configurable and by default is /platform/users group. The login module is not used because in normal environment, users are already in the /platform/users group. It is useful only for some special setups like read-only LDAP, where groups of ldap user are taken from ldap tree so that users may not be in the /platform/users group, which is needed for successful authorization.
  Note that CustomMembershipLoginModule can't be first login module in LM chain because it assumes that Identity object is already available in shared state. So there are those possible cases:

  • For non-SSO case, you may need to chain this LM with other login modules, which can be used to establish Identity and add it into shared state. Those LM can be InitSharedStateLoginModule and SharedStateLoginModule. See below.

  • For SSO (or OAuth) case, you can simply add CustomMembershipLoginModule between SSODelegateLoginModule and JBossAS7LoginModule.

Configuration example with CustomMembershipLoginModule and disabled SSO:

<login-module code="org.exoplatform.web.security.InitSharedStateLoginModule" flag="required">
  <module-option name="portalContainerName" value="portal"/>
  <module-option name="realmName" value="gatein-domain"/>
</login-module>
<login-module code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required">
  <module-option name="portalContainerName" value="portal"/>
  <module-option name="realmName" value="gatein-domain"/>
</login-module>
<login-module code="org.exoplatform.services.organization.idm.CustomMembershipLoginModule" flag="required">
  <module-option name="portalContainerName" value="portal"/>
  <module-option name="realmName" value="gatein-domain"/>
  <module-option name="membershipType" value="member" />
  <module-option name="groupId" value="/platform/users" />
</login-module>
<login-module code="org.exoplatform.services.security.j2ee.JBossAS7LoginModule" flag="required">
  <module-option name="portalContainerName" value="portal"/>
  <module-option name="realmName" value="gatein-domain"/>
</login-module>

And now configuration example with enabled SSO or OAuth:

<login-module code="org.gatein.security.oauth.jaas.OAuthLoginModule" flag="required">
  <module-option name="portalContainerName" value="portal"/>
  <module-option name="realmName" value="gatein-domain"/>
</login-module>
<login-module code="org.gatein.sso.integration.SSODelegateLoginModule" flag="required">
  <module-option name="enabled" value="#{gatein.sso.login.module.enabled}" />
  <module-option name="delegateClassName" value="#{gatein.sso.login.module.class}" />
  <module-option name="portalContainerName" value="portal" />
  <module-option name="realmName" value="gatein-domain" />
  <module-option name="password-stacking" value="useFirstPass" />
</login-module>
<login-module code="org.exoplatform.services.organization.idm.CustomMembershipLoginModule" flag="required">
  <module-option name="portalContainerName" value="portal"/>
  <module-option name="realmName" value="gatein-domain"/>
  <module-option name="membershipType" value="member" />
  <module-option name="groupId" value="/platform/users" />
</login-module>
<login-module code="org.exoplatform.services.security.j2ee.JBossAS7LoginModule" flag="required">
  <module-option name="portalContainerName" value="portal"/>
  <module-option name="realmName" value="gatein-domain"/>
</login-module>

• InitSharedStateLoginModule - It can read credentials from JAAS callback and add them into shared state. It's intended to be used in JAAS chain before SharedStateLoginModule

• SharedStateLoginModule- It reads username and password from sharedState map from attributes javax.security.auth.login.name and javax.security.auth.login.password. Then it calls Authenticator.validateUser(Credential[] credentials), to perform authentication of username and password against OrganizationService and portal identity database. Result of successful authentication is object Identity, which is saved to sharedState map .

Creating your own login module

Before creating your own login module, it is recommended you study source code of existing login modules to better understand the whole JAAS authentication process. You need to have good knowledge so that you can properly decide where your login module should be placed and if you need to replace some existing login modules or simply attach your own module to existing chain.

There are actually two levels of authentication and the overall result of JAAS authentication should properly handle both these cases:

• Authentication at application server level.

• Authentication at GateIn Portal level.

Authenticator and RolesExtractor

Authenticator is an important component in the authentication process. Actually interface org.exoplatform.services.security.Authenticator looks like this:

public interface Authenticator
{

   /**
    * Authenticate user and return userId.
    *
    * @param credentials - list of users credentials (such as name/password, X509
    *          certificate etc)
    * @return userId
    */
   String validateUser(Credential[] credentials) throws LoginException, Exception;

   /**
    * @param userId.
    * @return Identity
    */
   Identity createIdentity(String userId) throws Exception;

}

The validateUser method is used to check whether given credentials (username and password) are really valid. So it performs real authentication. It returns the username if credentials are correct. Otherwise, LoginException is thrown.

The createIdentity method is used to create instance of the org.exoplatform.services.security.Identity object, which encapsulates all important information about single user like:

• Username.

• Set of Memberships (MembershipEntry objects) which the user belongs to. Membership is object, which contains information about membershipType (manager, member, validator, and more) and about group (/platform/users, /platform/administrators, /partners, /organization/management/executiveBoard, and more).

• Set of Strings with JAAS roles of given user. JAAS roles are simple Strings, which are mapped from MembershipEntry objects. There is another special component org.exoplatform.services.security.RolesExtractor, which is used to map JAAS roles from MembershipEntry objects. RolesExtractor interface looks like this:

  public interface RolesExtractor
  {
  
     /**
      * Extracts J2EE roles from userId and|or groups the user belongs to both
      * parameters may be null
      *
      * @param userId
      * @param memberships
      */
     Set<String> extractRoles(String userId, Set<MembershipEntry> memberships);
  }

  The default implementation named DefaultRolesExtractorImpl is based on special algorithm, which uses name of role from the root of the group (for example you have JAAS role "organization" for the "/organization/management/something" role). The only exception is "platform" group where the second level is used as the group name. For example, from "/platform/users" group, you have the JAAS role "users".

Assuming that you have user root, which has memberships member:/platform/users, manager:/platform/administrators, validator:/platform/managers, member:/partners, member:/customers/acme, member:/organization/management/board. In this case, you will have JAAS roles: users, administrators, managers, partners, customers, organization.

Default implementation of Authenticator is OrganizationAuthenticatorImpl, which is implementation based on OrganizationService. See Organization API .

You can override the default implementation of mentioned interfaces (Authenticator and RolesExtractor) if the default behavior is not suitable for your needs.

RememberMe authentication

In default login dialog, you can notice that there is "Remember my login" checkbox, which users can use to persist their login on his workstation. Default validity period of RememberMe cookie is 1 day (it is configurable), and so user can be logged for whole day before he needs to reauthenticate again with his credentials.

Servlet container authorization

First round of authorization is servlet container authorization based on secured URL from web.xml. You can see above in the web.xml snippet that secured URL are accessible only for users from the users role:

<auth-constraint>
  <role-name>users</role-name>
</auth-constraint>

This actually means that your user needs to be in GateIn Portal role /platform/users (See Authenticator and RolesExtractor for details). In other words, if the authentication is successful but your user is not in the /platform/users group, it means that he is not in JAAS role users, which in next turn means that he will have authorization error named 403 Forbidden thrown by the servlet container. For example in LDAP setup, your users may not be in /platform/users by default, but you can use CustomMembershipLoginModule to fix this problem. For details see Login modules

You can change the behaviour and possibly add some more auth-constraint elements into web.xml. However, this protection of resources based on web.xml is not standard GateIn Portal way and it is mentioned here mainly for illustration purposes.

Portal level authorization

Second round of authorization is based on the UserACL component (See Portal Default Permission Configuration). You can declare access and edit permissions for portals, pages and/or portlets. UserACL is then used to check if our user has particular permissions to access or edit specified resource. Important object with information about roles of our user is mentioned Identity object created during the JAAS authentication.

Authorization on portal level looks like this:

• The user sends the HTTP request to some URLs in portal.

• The HTTP request is processed through SetCurrentIdentityFilter, which is declared in gatein/gatein.ear/portal.war/WEB-INF/web.xml.

• SetCurrentIdentityFilter reads username of current user from HttpServletRequest.getRemoteUser(). Then it looks for Identity of this user in IdentityRegistry, where Identity has been saved during authentication. The found Identity is then encapsulated into the ConversationState object and bound into the ThreadLocal variable.

• UserACL is able to obtain Identity of current user from the UserACL.getIdentity() method, which simply calls ConversationState.getCurrent().getIdentity() for finding the current Identity bound to ThreadLocal. Now UserACL has identity of user so that it can perform any security checks.